home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Hardware / Mac OS USB DDK / Mac OS USB DDK 1.4.1 / Examples / USBSampleStorageDriver / UnitTableDriver / UnitTableDeviceAccess.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-25  |  8.3 KB  |  173 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        UnitTableDeviceAccess.h
  3.  
  4.     Contains:    Required exported functions for Device Access Modules
  5.  
  6.     Version:    1.0
  7.  
  8.     Copyright:    © 1999-2000 by Apple Computer, Inc., all rights reserved.
  9.  
  10. */
  11.  
  12. #pragma once
  13.  
  14. #include <MacTypes.h>
  15. #include <NameRegistry.h>
  16. #include <Devices.h>
  17. #include <DriverGestalt.h>
  18.  
  19. #include "StorageClassPublicAPI.h"
  20.  
  21. // Errors reported by Device Access Module
  22. enum
  23. {
  24.     kDeviceAccessRequestPending    =    1,            // The request from the UTM is still be processed
  25.     kDeviceAccessNoMediaError     = -5000,        // There is currently no media in the drive
  26.     kDeviceAccessMediaUnusable,                    // The media can not be used by this driver, request that it be ejected
  27.     kDeviceAccessNotAvailable,                    // The device cannot currently be accessed
  28.     kDeviceAccessDataTransferErrorOccurred,        // The data was not transferred - request may be retried
  29.     kDeviceAccessInterfaceCommunicationsError    // The request could not be sent to the device - device is not responding or is gone
  30. };
  31.  
  32. // ---------------------- Query Functions ------------------------------
  33. // These functions do not require a callback routine, and always returns
  34. // the result immediately.  These are used to determine state of the
  35. // DAM or the device and should be set up by the DAM during the initializtion
  36. // process.  These should not cause device access.
  37. // ---------------------------------------------------------------------
  38.  
  39. // Returns true if access to the device through the appropiate I/O manager is possible.
  40. extern Boolean        IsDeviceAccessEnabled( void );
  41.  
  42. // GetDriverGestaltIntfForInterface - returns the OSType for the interface
  43. // supported by the DAM.  The interface types are defined in DriverGestalt.h
  44. extern OSType         GetDriverGestaltIntfForInterface( void );
  45.  
  46. // GetDeviceReferenceNumber - returns a UInt32 that holds the device reference 
  47. // number for this device.  This number is interpretted differently depending
  48. // on the 'intf' value and the interpretation is defined in DriverGestalt.h
  49. extern UInt32         GetDeviceReferenceNumber( void );
  50.  
  51. // GetDeviceInfoPtr - returns a pointer to the Device Info structure.
  52. // The Device Info structure is defined in DriverGesalt.h
  53. extern DriverGestaltDeviceModelInfoResponse *GetDeviceInfoPtr( void );
  54.  
  55. // GetDriverVersionNumber - returns the version number for this driver.
  56. // The Device Info structure is defined in DriverGesalt.h
  57. extern void GetDriverVersionNumber( NumVersion *theVersion );
  58.  
  59. // GetInterfaceNameString - returns a pascal string of the name of
  60. // the interface supported by the DAM.  Used for the driver's "where" string.
  61. extern StringPtr    GetDeviceWhereString( void );
  62.  
  63. // GetSupportedMediaTypesPtr - returns a pointer to the supported media structure.
  64. // The Supported Media Types structure is defined in DriverGesalt.h
  65. typedef struct SupportedMediaStruct
  66. {
  67.     UInt32        supportTypesCount;        /* The number of Media Types in the array */
  68.     OSType        supportedTypesArray[4];    /* Array of supported media types  */
  69. } SupportedMediaStruct;
  70.  
  71. extern DriverGestaltSupportedMediaTypesResponse *GetSupportedMediaTypesPtr( void );
  72.  
  73. // This query function is used to determine if this interface should be allowed 
  74. // to be used for Virtual Memory page mapping.  If the DAM returns false,  the
  75. // driver not allow any VM usage on the attached device.  If the returned value
  76. // is true, the UnitTable module will determine what VM options should be allowed
  77. // based on the device type, media type and write protect status.
  78. extern Boolean         DoesInterfaceHaveVirtualMemoryCapabilities( void );
  79.  
  80. // Query function for getting the MediaProperties
  81. // This function will return information about the media currently in the device.
  82. extern void         GetMediaProperties ( UInt32 *TotalBlocksOnMedia, UInt32 *BlockLengthInBytes, Boolean *IsWriteProtected, OSType *currentType );
  83.  
  84. // ---------------------- Action Functions -----------------------------
  85. // Each of these functions require a callback procedure pointer and will
  86. // be performed asynchronously
  87. // ---------------------------------------------------------------------
  88. // The default completion routine pointer.  All completion routines must contain
  89. // at least these two return parameters. If the completion routine does not need
  90. // to return any other data, it should be of this type, else an extension of this type.
  91. typedef CALLBACK_API_C    ( void, DefaultDAMCompletionProcPtr ) (
  92.             UInt32        userData,
  93.             OSStatus    status );
  94.  
  95. // Initialize routine - called to enable access to the device and interface.
  96. // Must be called before the driver can access the device.
  97. // This routine may allocate memory so it must be called at task time
  98. typedef DefaultDAMCompletionProcPtr InitializeCompletionProcPtr;
  99. extern OSStatus     InitializeDeviceAccess(  DriverRefNum theRefNum, RegEntryIDPtr theRegEntryPtr );
  100.  
  101. // Terminate routine - called to terminate access to the device or interface.
  102. // Must be called when the driver is closed to free up resources used by the Device Access Module.
  103. // This routine may deallocate memory so it must be called at task time.
  104. typedef DefaultDAMCompletionProcPtr TerminateCompletionProcPtr;
  105. extern OSStatus     TerminateDeviceAccess(  DriverRefNum theRefNum, RegEntryIDPtr theRegEntryPtr );
  106.  
  107. // Control and Status entry points.  Any control or status call that is not handled by the UnitTable
  108. // Module will be sent to the Device Access Module since the call may be interface specific or, when
  109. // sopported, may be for a Device Specific Module.
  110. typedef DefaultDAMCompletionProcPtr     ControlStatusCompletionProcPtr;
  111. extern OSStatus        HandleControlRequest (    UInt32                            userData,
  112.                                                 CntrlParamPtr                    cntrlPBPtr,
  113.                                                 ControlStatusCompletionProcPtr    callBack );
  114.     
  115. extern OSStatus        HandleStatusRequest (    UInt32                            userData,
  116.                                                 CntrlParamPtr                    cntrlPBPtr,
  117.                                                 ControlStatusCompletionProcPtr    callBack );
  118.  
  119. // Check for media entry point.  When the DAM calls the completion routine for this request when
  120. // media was detected, the DAM will have already determined everything it needs to know about the
  121. // media.  These include things like media capacity, if the media is write protected and the type
  122. // of media that was detected.
  123. typedef DefaultDAMCompletionProcPtr CheckIfMediaIsPresentCompletionProcPtr;
  124. extern OSStatus        CheckIfMediaIsPresent( UInt32 userData, CheckIfMediaIsPresentCompletionProcPtr callBack );
  125.  
  126. // Lock Media entry point
  127. // Locks the media. If a user presses the eject button the media will not be ejected.
  128. typedef DefaultDAMCompletionProcPtr LockMediaCompletionProcPtr;
  129. extern OSStatus     PreventMediaRemoval( UInt32    userData, LockMediaCompletionProcPtr callBack );
  130.  
  131. // Unlock Media entry point
  132. // Unlocks the media. If a user presses the eject button the media will be ejected.
  133. typedef DefaultDAMCompletionProcPtr UnlockMediaCompletionProcPtr;
  134. extern OSStatus     AllowMediaRemoval( UInt32 userData, UnlockMediaCompletionProcPtr callBack );
  135.  
  136. // Eject Cartridge entry point
  137. typedef DefaultDAMCompletionProcPtr EjectCartridgeCompletionProcPtr;
  138. extern OSStatus     EjectCartridge( UInt32 userData, EjectCartridgeCompletionProcPtr    callBack );
  139.  
  140. // Flush Write cache entry point
  141. // Causes the device to write any cached data to the media
  142. typedef DefaultDAMCompletionProcPtr FlushCacheCompletionProcPtr;
  143. extern OSStatus     FlushDriveWriteCache( UInt32 userData, FlushCacheCompletionProcPtr callBack );
  144.  
  145. // Read/Write a single buffer entry point
  146. typedef DefaultDAMCompletionProcPtr RWBlocksCompletionProcPtr;
  147. extern OSStatus     ReadWriteSingleBuffer( UInt32 userData, UInt32 startBlock, UInt32 blockCount, Ptr buffer, 
  148.             UInt32 byteCount, Boolean doWrite, RWBlocksCompletionProcPtr callBack );
  149.  
  150. // Read/Write a scatter-gather list entry point
  151. struct SGElement {
  152.     Ptr             SGAddr;
  153.     UInt32             SGCount;
  154. };
  155. typedef struct SGElement    SGElement, *SGElementPtr;
  156.  
  157. struct SGList
  158. {
  159.     UInt32            sgNumberElements;
  160.     SGElementPtr    sgElementList;    
  161. };
  162.  
  163. typedef struct SGList SGList, *SGListPtr;
  164.  
  165. typedef DefaultDAMCompletionProcPtr RWScatterGatherCompletionProcPtr;
  166. extern OSStatus     ReadWriteScatterGatherList( UInt32 userData, UInt32 startBlock, UInt32 blockCount, SGListPtr sgList, 
  167.             UInt32 byteCount, Boolean doWrite, RWScatterGatherCompletionProcPtr callBack );
  168.  
  169. // Format the Media entry point.  When the completion routine is called, the DAM will have already determined if the format was
  170. // successful, and will get the new capacity of the media.
  171. typedef DefaultDAMCompletionProcPtr FormatMediaCompletionProcPtr;
  172. extern OSStatus     FormatMedia( UInt32 userData, UInt32 FormatCapacity, UInt16 blockSize, FormatMediaCompletionProcPtr    callBack );
  173.